Pix Transfer with key

To perform a Pix transfer with a key, it is necessary to first query the key information through the payment initiation endpoint and finally carry out the transfer.

Payment Initialization

This endpoint will provide you with basic data relating to the queried key. Additionally, it will provide the "endToEndId" attribute that will be required by the transfer endpoint if you choose Pix with key.

Info

In the staging environment you'll only be able to make transfers to keys that exist in the staging environment.

Pix Keys examples

Note that a Pix transfer cannot me made from an account to itself.

beneficiary Account	Key	Type
31712	+5511999975734	PHONE
31712	[email protected]	EMAIL
31712	1aa5ef56-3b5f-4665-9ece-e7513efc03e5	EVP
29823	30287697789	DOCUMENT
29823	0a192461-051f-438b-b9c4-2db423039281	EVP
29823	30287697789	DOCUMENT
30422	06790157000144	DOCUMENT
30422	255d38b2-42c1-4593-844d-8e92bd6cb438	EVP
30422	790aa11-8199-40f5-bfad-6ab99a73ab3a	EVP

Below is a request and response example. For more information about the endpoint, click here.

Request

URL

POST 'https://apisandbox.delbank.com.br/baas/api/v2/pix/dict/payment-initialization'

cURL

curl --location 'https://apisandbox.delbank.com.br/baas/api/v2/pix/dict/payment-initialization' \
--header 'x-delbank-api-key: PJPyJ2xGmyB9oDHyNIUwNOt1dgpgolBwcE16ybaKD5q5eXIoHXNudlu+EaCcwXyLnryGdeBNfqofzLQe9f7s/iMVnsMZrbAPO/cYn6pTQEHVErYL080/hmZYV8faI89D' \
--header 'Content-Type: application/json' \
--data '{
    "key": "+5511999975734"
}'

Headers

Name	Description
x-delbank-api-key	Required. API key

Body

Name	Type	Description
key	string	Required. Pix Key registered in the DICT.
holderDocument	string	Optional. Holder's document to verify if they are the owner of the key being searched. If this field is provided, the Pix key search response will return a FLAG indicating (keyBelongsHolder) whether the key belongs to this holder.

Response

The status code 200 will indicate success in the transaction.

Being successful, the return will bring the following field in JSON format:

Note

🚧 Use the endToEndId attribute in the transfer request.

{
    "endToEndId": "E38224857202412201244TP05NXG36QK",
    "key": "30287697789",
    "beneficiary": {
        "number": "29823",
        "branch": "1",
        "type": "CURRENT",
        "participant": {
            "name": "DELCRED SCD S.A.",
            "ispb": "38224857"
        },
        "holder": {
            "name": "HOMOLOGACAO INTEGRACAO API",
            "document": "***876977**",
            "type": "NATURAL"
        }
    },
    "keyBelongsHolder": false
}

If the correct holderDocument is passed, the response will be like this:

{
    "endToEndId": "E3822485720241220122418yWF7jWUKA",
    "key": "30287697789",
    "beneficiary": {
        "number": "29823",
        "branch": "1",
        "type": "CURRENT",
        "participant": {
            "name": "DELCRED SCD S.A.",
            "ispb": "38224857"
        },
        "holder": {
            "name": "HOMOLOGACAO INTEGRACAO API",
            "document": "***876977**",
            "type": "NATURAL"
        }
    },
    "keyBelongsHolder": true
}

Carrying out the payment

After the payment initialization, verify the payee account associated with the returned endToEndId. Execute the transfer endpoint API calling.

Request

URL

POST 'https://apisandbox.delbank.com.br/baas/api/v2/transfers

cURL

curl --request POST \
     --url https://apisandbox.delbank.com.br/baas/api/v2/transfers \
     --header 'IdempotencyKey: 9d16ea35-8a85-49ea-a41e-bcf56c677129' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-delbank-api-key: {{apiKey}}' \
     --data '
{
    "amount": 0.01,
    "description": "description",
    "endToEndId": "E3822485720230814223254707809687",
    "initiationType": "KEY"
}
'

Headers

Name	Description
x-delbank-api-key	Required. API key
IdempotencyKey	Required. Request's idempotency key. Provide a GUID, being a new one for each request..

Body

Name	Type	Description
amount	number	Required. Transfer amount.
description	string	Description about the transfer. This information will be shown as beneficiary
endToEndId	string	Required. EndToEndId returned while consulting a DICT key
initiationType	enum	Required. Initialization type. Use the type 'KEY' in this case

Response

The status code 200 ensures that the transaction has succeeded.

Being successful, the return will bring the following field in JSON format:

Note

🚧 The information will be return after the transfer initialization and the consulting the transfer.

{
    "id": "0fc7821d-b488-4268-88c0-a2bc443d046e",
    "endToEndId": "E3822485720230808004731LMaDWkOcM",
    "transactionNsu": 722355,
    "status": "PIX_PROCESSING",
    "type": "PIX_KEY",
    "amount": 0.55,
    "createdAt": "2023-08-08T00:47:31.251Z",
    "description": "manual JD",
    "payer": {
        "number": "31712",
        "branch": "0001",
        "type": "CURRENT",
        "holder": {
            "document": "32752023000149",
            "name": "bxxdbde",
            "type": "LEGAL"
        },
        "participant": {
            "name": "DELBANK",
            "ispb": "38224857"
        }
    },
    "beneficiary": {
        "number": "46441",
        "branch": "0007",
        "type": "CURRENT",
        "holder": {
            "document": "01234567890",
            "name": "CICLANO FULANO",
            "type": "NATURAL"
        },
        "participant": {
            "name": "BANCO DA AMAZONIA S.A.",
            "ispb": "04902979"
        }
    }
}

Pix Status

Name	Description
PIX_ERROR	There was an error with the transfer
PIX_PROCESSING	The transfer is being processed
PIX_WAITING_SPI_RESPONSE	The transfer is waiting SPI response
PIX_EFFECTIVE	The transfer was successful
PIX_REFUND_PAYMENT_UPDATED	Event for sent refunds

info

📘 For more information

For more information and simulations about this endpoint requisition, access the API Reference.